/**
 * @file 全局状态类型定义
 * @description 定义全局状态管理库中使用的所有类型和接口
 * @author 黄敏
 * @created 2025-06-16
 * @updated 2025-01-27 优化注释和文档，移除冗余示例
 */

/**
 * 命令ID枚举（与主进程快捷键命令分发一一对应）
 * 用于限制快捷键映射到的命令范围，保持类型安全。
 */
export type CommandId =
  | 'cmd:tab:new' // 新建标签页
  | 'cmd:tab:close' // 关闭当前标签页
  | 'cmd:tab:reload' // 重新加载当前标签页
  | 'cmd:find:toggle' // 显示查找框
  | 'cmd:settings:open' // 打开设置面板
  | 'cmd:devtools:toggle' // 显示开发工具

/**
 * 快捷键配置接口
 * @description 定义单个快捷键的结构，包含名称和按键组合
 */
export interface Shortcut {
  /** 命令ID，用于执行与唯一识别（例如：'tab:new'） */
  id: CommandId
  /** 快捷键名称，用于显示和识别 */
  name: string
  /** 快捷键组合，如 'Ctrl+C', 'Ctrl+Shift+S' 等 */
  key: string
  /** 是否启用该快捷键（默认启用） */
  enabled?: boolean
}

/**
 * 窗口状态接口
 * @description 定义窗口的尺寸、位置和状态信息
 * 继承自 Record<string, unknown> 以支持动态属性扩展
 */
export interface WindowState extends Record<string, unknown> {
  /** 窗口宽度（像素） */
  width: number
  /** 窗口高度（像素） */
  height: number
  /** 右侧边栏宽度（像素） */
  rightWidth: number
  /** 窗口是否最大化 */
  isMaximized: boolean
  /** 窗口X坐标（像素），可选属性 */
  x?: number
  /** 窗口Y坐标（像素），可选属性 */
  y?: number
}

/**
 * 用户自定义快捷键覆盖项
 * 仅保存与默认值不同的差异项（按命令ID覆盖 key/enabled）
 */
export type ShortcutOverride = {
  key?: string
  enabled?: boolean
}

/**
 * 快捷键配置接口（持久化）
 * 仅保存 overrides；实际使用时与默认值合并得到有效快捷键
 */
export type ShortcutsConfig = {
  /** 差异化覆盖：只保存用户改动 */
  overrides: Record<CommandId, string>
}
